Skip to content

Android: an upload with no network sleeps until Android reports a working network - #91

Open
dmurphy5 wants to merge 12 commits into
dylan/android-clear-waitfrom
dylan/android-network-wake
Open

dmurphy5 wants to merge 12 commits into
dylan/android-clear-waitfrom
dylan/android-network-wake

Conversation

@dmurphy5

@dmurphy5 dmurphy5 commented Nov 18, 2026 •

Copy link
Copy Markdown

What was wrong

An Android upload with no network stayed in a running WorkManager job and checked the network every 10 s. Android counts that time against the app's job quota (in the rare standby bucket, 10 minutes in 24 hours) and stops the job at its time limit. With the change below this one, a run that only waited starts again at once after such a stop, so an offline upload could start, poll and stop without end.

What changes

On API 30 and later:

  • A run with no foreground mode that finds no usable network waits at most 60 s. A run with foreground mode waits at most 30 minutes in an app that targets API 35, on Android 15 and later (the dataSync limit of 6 hours in 24 applies to those apps); otherwise it polls as before.
  • Then the entry goes back to queued with no row of its own. No attempt, no backoff step, no wait cause.
  • It waits on a doorbell: one WorkManager row for the whole queue that waits for a validated network, and one that waits for validated Wi-Fi. When Android starts a doorbell, its worker sends nothing. It starts each waiting entry whose network fits on an ordinary row (also an entry whose hand-over worker is still leaving), waits until those rows are stored, and keeps a doorbell for the rest. It never fails: any error is a retry. When the library's own check refuses a network that WorkManager saw, the next ring comes at least 30 s later (a hand-over during that ring, or a repair that replaces a held-back doorbell, can add one ring with no delay).
  • No row that runs an upload has a network rule, so WorkManager never stops an upload because a rule is lost. Backoff and expiry wakes have no rule, as before. At most two rows sleep for all waiting entries.
  • The boot sweep, resume(), a return to the foreground, a same-id mutate() and setWifiOnly() start a waiting entry only when the network fits it now. Otherwise they make sure its doorbell exists. So an app start with no network starts nothing, and an app opened with a network does not depend on the doorbell.
  • A run hands over only while none of its requests is sending. Each attempt checks the network again inside its transmit slot; a failed check leaves the slot with no attempt counted.
  • A Wi-Fi-only run waits while the app binds the process to a network that is not Wi-Fi. It keeps waiting in the run instead of handing over.
  • The network check never throws; an error reads as no network.
  • The boot record has wifiOnly, entriesByWake and doorbells, from the state before the boot sweep.
  • A WorkManager call that times out (10 s) does not make mutate(), resume() or updateHeaders() reject, and does not stop the boot sweep. A pass stops scheduling at the first timeout and writes one record; the library then runs a repair on its queue thread (30 s, doubling to 5 minutes) that starts every queued entry with no row. A doorbell ring that times out stops and rings again.

API 29 keeps the poll and has no doorbell.

flowchart TD
  A[Run checks the network] -->|fits| S[Take a slot, check again, send]
  S -->|no longer fits| A
  A -->|does not fit| B{Waited 60 s, or 30 min with foreground mode in an app that targets API 35?}
  B -->|no| P[Wait 10 s] --> A
  B -->|yes| C{A request of this run is sending?}
  C -->|yes| P
  C -->|no| D[Entry back to queued, no row of its own]
  D --> E[Doorbell row with the network rule, one per rule for the whole queue]
  E -->|Android reports the network| F[Doorbell starts the entries whose network fits]
  F --> A
Loading

Behavior change

  • An offline upload no longer holds a running job, and an app start with no network starts no run.
  • setWifiOnly(false) starts the waiting entries at once when a network fits.
  • A Wi-Fi-only upload waits while the process is bound to cellular, and a request that waited for a transmit slot does not go out on a network that no longer fits.
  • A network check that throws makes the upload wait. Before, it settled the upload as failed.
  • An entry whose expiresAt passes while it waits for a doorbell settles expired when its next run starts.
  • Known limits: an offline app start shows no waiting notification. A run that a doorbell starts in the background cannot take foreground mode on API 31 and later, so a single body that needs more than the 10-minute job limit cannot finish until the app is opened. With 20 or more older sleeping rows the doorbell is not handed to JobScheduler until some of them have run.

Tests

  • NetworkDoorbellTest uses a WorkManager fake that models network rules, a constraint stop of a running row, a worker that returns retry or fails, a late insert failure, and the 20-row JobScheduler limit. It covers what starts an entry in each state: after a hand-over, with a hand-over worker still leaving (both orders), a lost doorbell, a doorbell stopped by its own rule, a doorbell rung with the app process dead, 250 entries on the Wi-Fi doorbell next to an entry that may use cellular, every repair online and offline, and rule changes while waiting. Rings are at least 30 s apart when the library refuses. After every test it checks that no upload row has a network rule.
  • EntryRunTest: the 60 s hand-over, the 30-minute cap (API 35 device and target only), API 29, the bind, a throwing check, the in-slot check for a simple request and a chunked part, a failed doorbell, the send gate and its reset per pass.
  • QueueControllerTest and RequiredNetworkTest: setWifiOnly, the boot record, and the rule tables.
  • Each fix was broken on purpose and a test failed.

Three independent review rounds were applied. Stacked on #88. The stop-rule PR #85 must ship in the same release as this one.

🤖 Generated with Claude Code

dmurphy5 and others added 10 commits November 17, 2026 19:30
…e network

On API 30 and later, a run with no foreground mode that finds no usable
network waits at most 60 s, then goes back to queued and sleeps on a wake
row with a WorkManager network rule (CONNECTED, or a validated Wi-Fi
request for a Wi-Fi-only entry). A run with foreground mode waits at most
30 minutes first. No attempt, backoff step, wait cause or nextAttemptAt is
written. A run hands over only while none of its requests is sending.

Backoff wakes and the wake after a time-limit stop also wait for a
network; a parked entry's expiry wake does not. API 29 keeps the poll and
unconstrained wakes. The sweep, resume() and a same-id enqueue keep a
network wake; retryNow() adds a main row next to it only when the network
fits now. setWifiOnly(false) runs the queued entries that follow it. The
boot record counts entries by wake kind and reports wifiOnly. A Wi-Fi-only
upload also waits while the process is bound to a network that is not
Wi-Fi.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CHANGELOG (Unreleased, behavior change), README Android notes, setWifiOnly
and the boot record fields, and the BootWakeCounts type for
entriesByWake and wifiOnly, with type tests.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…onstrained row

The review found that rows with a network rule let WorkManager stop an
upload mid-request when the rule is lost, and then hold the stopped row
back for hours; that the repair paths left two rows per entry; and that
many sleeping constrained wakes could fill WorkManager's slots.

Now no row that runs an upload has a WorkManager constraint. A run that
hands over goes back to queued with no row of its own and makes sure one
of two doorbell rows exists (any validated network, or validated Wi-Fi).
The doorbell's worker sends nothing: it starts each waiting entry whose
network fits on an ordinary main row, and keeps a doorbell for the rest.
Its enqueue is awaited. Backoff and expiry wakes have no rule again.

The boot sweep, resume(), a foreground, a same-id enqueue and
setWifiOnly() start a waiting entry only when the network fits it now,
else they make sure its doorbell exists: one row per entry, and an
offline app start starts nothing. A failed doorbell falls back to the
main row. The network check never throws and is read at most twice per
pass. A Wi-Fi-only run bound to cellular keeps waiting instead of handing
over. The 30-minute foreground cap applies on API 35 and later only. The
send gate is new for every pass. The boot record reports the doorbells.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
CHANGELOG (Unreleased) and README describe the doorbell design, the
repair rules, the 30-minute foreground cap on API 35 and later with its
known limit, and the boot record's doorbells field. BootDoorbells type
and type tests.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
From the second review of the doorbell design:

- A doorbell no longer skips an entry because a worker or a RUNNING row
  of it exists: that can be a worker that handed over and is leaving. It
  skips only an entry with an ENQUEUED row that starts now; for the others
  schedule() queues one row behind the running one. setWifiOnly() too.
- The doorbell worker returns retry on any error, never failure, so a
  doorbell queued behind it is not failed with it.
- A doorbell insert that fails is tried once per pass; the other entries
  of that rule get their main row, with one diagnostics record.
  WorkManager queries before an insert have a timeout.
- retryNow treats a short or due wait as no wait, so an entry with a kept
  sibling wait follows the network rule and starts nothing offline.
- awaitNetwork schedules the entry's wake when its kept wait reads long.
- A doorbell whose network the library's check refuses queues the next
  one with a 30 s delay.
- The doorbell waits until each main row is stored, and retries if not.
- Each attempt checks the network again inside the transmit slot; on a
  failed check it leaves the slot with no attempt and waits again.
- The 30-minute foreground cap needs a target of API 35 too.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…seconds

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
From the delta review of the doorbell design:

- enqueue, resume, updateHeaders, the boot sweep, retryNow and
  setWifiOnly catch a scheduling failure per entry. At the first
  WorkManager timeout a pass stops scheduling, writes one diagnostics
  record and asks for a repair; mutate() resolves once the entry is
  saved, and the sweep still writes its boot record.
- repairRows() runs on the queue executor after 30 s, doubling to
  5 minutes while it fails, and starts every queued entry that has no row
  that can start now (main row or doorbell) and makes missing wakes.
- A doorbell ring stops at the first timeout with one record and returns
  retry.
- The WorkManager library query also times out after 10 s.
- The ring-spacing test covers ten minutes and asserts the gaps.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ions

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@dmurphy5
dmurphy5 added this pull request to stack #89 November 18, 2026 18:13
@dmurphy5 dmurphy5 changed the title dylan/android network wake Android: an upload with no network sleeps until Android reports a working network Nov 18, 2026
dmurphy5 and others added 2 commits November 18, 2026 13:20
From the third check of the doorbell design:

- After a WorkManager timeout, while its repair is pending, a new pass
  makes no WorkManager call and leaves its entries to that repair, which
  has not read the store yet. Five enqueues now cost one timed-out query.
  A repair that schedules with no failure clears the state.
- The boot sweep feeds a timeout of its run query into its pass, so it
  waits once, not twice.
- CHANGELOG: the repair timer lives in memory; after a process death the
  boot sweep or a doorbell ring starts the entry.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Two mutations survived the previous commit: the repair pass never skips,
because its task clears the pending flag first, so its extra guard did
nothing; and no test showed the timeout being cleared. The guard is
removed (the order is now the tested rule), and the test adds a later
failure that is not a timeout: passes meanwhile still schedule.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant